<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>TLS Overview</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="tls.html" title="TLS (SSL) support">
<link rel="prev" href="tls.html" title="TLS (SSL) support">
<link rel="next" href="GTlsCertificate.html" title="GTlsCertificate">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="tls.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="tls.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GIO Reference Manual</th>
<td><a accesskey="n" href="GTlsCertificate.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#gio-TLS-Overview.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#gio-TLS-Overview.description" class="shortcut">Description</a>
</td></tr>
</table>
<div class="refentry">
<a name="gio-TLS-Overview"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="gio-TLS-Overview.top_of_page"></a>TLS Overview</span></h2>
<p>TLS Overview — TLS (aka SSL) support for GSocketConnection</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="gio-TLS-Overview.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;gio/gio.h&gt;

#define             <a class="link" href="gio-TLS-Overview.html#G-TLS-ERROR:CAPS" title="G_TLS_ERROR">G_TLS_ERROR</a>
enum                <a class="link" href="gio-TLS-Overview.html#GTlsError" title="enum GTlsError">GTlsError</a>;

enum                <a class="link" href="gio-TLS-Overview.html#GTlsAuthenticationMode" title="enum GTlsAuthenticationMode">GTlsAuthenticationMode</a>;
enum                <a class="link" href="gio-TLS-Overview.html#GTlsCertificateFlags" title="enum GTlsCertificateFlags">GTlsCertificateFlags</a>;
</pre>
</div>
<div class="refsect1">
<a name="gio-TLS-Overview.description"></a><h2>Description</h2>
<p>
<a class="link" href="GTlsConnection.html" title="GTlsConnection"><span class="type">GTlsConnection</span></a> and related classes provide TLS (Transport Layer
Security, previously known as SSL, Secure Sockets Layer) support for
gio-based network streams.
</p>
<p>
In the simplest case, for a client connection, you can just set the
<a class="link" href="GSocketClient.html#GSocketClient--tls" title='The "tls" property'><span class="type">"tls"</span></a> flag on a <a class="link" href="GSocketClient.html" title="GSocketClient"><span class="type">GSocketClient</span></a>, and then any
connections created by that client will have TLS negotiated
automatically, using appropriate default settings, and rejecting
any invalid or self-signed certificates (unless you change that
default by setting the <a class="link" href="GSocketClient.html#GSocketClient--tls-validation-flags" title='The "tls-validation-flags" property'><span class="type">"tls-validation-flags"</span></a>
property). The returned object will be a <a class="link" href="GTcpWrapperConnection.html" title="GTcpWrapperConnection"><span class="type">GTcpWrapperConnection</span></a>,
which wraps the underlying <a class="link" href="GTlsClientConnection.html" title="GTlsClientConnection"><span class="type">GTlsClientConnection</span></a>.
</p>
<p>
For greater control, you can create your own <a class="link" href="GTlsClientConnection.html" title="GTlsClientConnection"><span class="type">GTlsClientConnection</span></a>,
wrapping a <a class="link" href="GSocketConnection.html" title="GSocketConnection"><span class="type">GSocketConnection</span></a> (or an arbitrary <a class="link" href="GIOStream.html" title="GIOStream"><span class="type">GIOStream</span></a> with
pollable input and output streams) and then connect to its signals,
such as <a class="link" href="GTlsConnection.html#GTlsConnection-accept-certificate" title='The "accept-certificate" signal'><span class="type">"accept-certificate"</span></a>, before starting the
handshake.
</p>
<p>
Server-side TLS is similar, using <a class="link" href="GTlsServerConnection.html" title="GTlsServerConnection"><span class="type">GTlsServerConnection</span></a>. At the
moment, there is no support for automatically wrapping server-side
connections in the way <a class="link" href="GSocketClient.html" title="GSocketClient"><span class="type">GSocketClient</span></a> does for client-side
connections.
</p>
</div>
<div class="refsect1">
<a name="gio-TLS-Overview.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="G-TLS-ERROR:CAPS"></a><h3>G_TLS_ERROR</h3>
<pre class="programlisting">#define G_TLS_ERROR (g_tls_error_quark ())
</pre>
<p>
Error domain for TLS. Errors in this domain will be from the
<a class="link" href="gio-TLS-Overview.html#GTlsError" title="enum GTlsError"><span class="type">GTlsError</span></a> enumeration. See <a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> for more information on error
domains.
</p>
</div>
<hr>
<div class="refsect2">
<a name="GTlsError"></a><h3>enum GTlsError</h3>
<pre class="programlisting">typedef enum {
  G_TLS_ERROR_UNAVAILABLE,
  G_TLS_ERROR_MISC,
  G_TLS_ERROR_BAD_CERTIFICATE,
  G_TLS_ERROR_NOT_TLS,
  G_TLS_ERROR_HANDSHAKE,
  G_TLS_ERROR_CERTIFICATE_REQUIRED,
  G_TLS_ERROR_EOF
} GTlsError;
</pre>
<p>
An error code used with <a class="link" href="gio-TLS-Overview.html#G-TLS-ERROR:CAPS" title="G_TLS_ERROR"><code class="literal">G_TLS_ERROR</code></a> in a <a href="./../glib/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> returned from a
TLS-related routine.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-TLS-ERROR-UNAVAILABLE:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_UNAVAILABLE</code></span></p></td>
<td>No TLS provider is available
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-MISC:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_MISC</code></span></p></td>
<td>Miscellaneous TLS error
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-BAD-CERTIFICATE:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_BAD_CERTIFICATE</code></span></p></td>
<td>A certificate could not be parsed
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-NOT-TLS:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_NOT_TLS</code></span></p></td>
<td>The TLS handshake failed because the
  peer does not seem to be a TLS server.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-HANDSHAKE:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_HANDSHAKE</code></span></p></td>
<td>The TLS handshake failed because the
  peer's certificate was not acceptable.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-CERTIFICATE-REQUIRED:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_CERTIFICATE_REQUIRED</code></span></p></td>
<td>The TLS handshake failed because
  the server requested a client-side certificate, but none was
  provided. See <a class="link" href="GTlsConnection.html#g-tls-connection-set-certificate" title="g_tls_connection_set_certificate ()"><code class="function">g_tls_connection_set_certificate()</code></a>.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-ERROR-EOF:CAPS"></a><span class="term"><code class="literal">G_TLS_ERROR_EOF</code></span></p></td>
<td>The TLS connection was closed without proper
  notice, which may indicate an attack. See
  <a class="link" href="GTlsConnection.html#g-tls-connection-set-require-close-notify" title="g_tls_connection_set_require_close_notify ()"><code class="function">g_tls_connection_set_require_close_notify()</code></a>.
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.28</p>
</div>
<hr>
<div class="refsect2">
<a name="GTlsAuthenticationMode"></a><h3>enum GTlsAuthenticationMode</h3>
<pre class="programlisting">typedef enum {
  G_TLS_AUTHENTICATION_NONE,
  G_TLS_AUTHENTICATION_REQUESTED,
  G_TLS_AUTHENTICATION_REQUIRED
} GTlsAuthenticationMode;
</pre>
<p>
The client authentication mode for a <a class="link" href="GTlsServerConnection.html" title="GTlsServerConnection"><span class="type">GTlsServerConnection</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-TLS-AUTHENTICATION-NONE:CAPS"></a><span class="term"><code class="literal">G_TLS_AUTHENTICATION_NONE</code></span></p></td>
<td>client authentication not required
</td>
</tr>
<tr>
<td><p><a name="G-TLS-AUTHENTICATION-REQUESTED:CAPS"></a><span class="term"><code class="literal">G_TLS_AUTHENTICATION_REQUESTED</code></span></p></td>
<td>client authentication is requested
</td>
</tr>
<tr>
<td><p><a name="G-TLS-AUTHENTICATION-REQUIRED:CAPS"></a><span class="term"><code class="literal">G_TLS_AUTHENTICATION_REQUIRED</code></span></p></td>
<td>client authentication is required
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.28</p>
</div>
<hr>
<div class="refsect2">
<a name="GTlsCertificateFlags"></a><h3>enum GTlsCertificateFlags</h3>
<pre class="programlisting">typedef enum {
  G_TLS_CERTIFICATE_UNKNOWN_CA    = (1 &lt;&lt; 0),
  G_TLS_CERTIFICATE_BAD_IDENTITY  = (1 &lt;&lt; 1),
  G_TLS_CERTIFICATE_NOT_ACTIVATED = (1 &lt;&lt; 2),
  G_TLS_CERTIFICATE_EXPIRED       = (1 &lt;&lt; 3),
  G_TLS_CERTIFICATE_REVOKED       = (1 &lt;&lt; 4),
  G_TLS_CERTIFICATE_INSECURE      = (1 &lt;&lt; 5),
  G_TLS_CERTIFICATE_GENERIC_ERROR = (1 &lt;&lt; 6),

  G_TLS_CERTIFICATE_VALIDATE_ALL  = 0x007f
} GTlsCertificateFlags;
</pre>
<p>
A set of flags describing TLS certification validation. This can be
used to set which validation steps to perform (eg, with
<a class="link" href="GTlsClientConnection.html#g-tls-client-connection-set-validation-flags" title="g_tls_client_connection_set_validation_flags ()"><code class="function">g_tls_client_connection_set_validation_flags()</code></a>), or to describe why
a particular certificate was rejected (eg, in
<a class="link" href="GTlsConnection.html#GTlsConnection-accept-certificate" title='The "accept-certificate" signal'><span class="type">"accept-certificate"</span></a>).
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-UNKNOWN-CA:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_UNKNOWN_CA</code></span></p></td>
<td>The signing certificate authority is
  not known.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-BAD-IDENTITY:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_BAD_IDENTITY</code></span></p></td>
<td>The certificate does not match the
  expected identity of the site that it was retrieved from.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-NOT-ACTIVATED:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_NOT_ACTIVATED</code></span></p></td>
<td>The certificate's activation time
  is still in the future
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-EXPIRED:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_EXPIRED</code></span></p></td>
<td>The certificate has expired
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-REVOKED:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_REVOKED</code></span></p></td>
<td>The certificate has been revoked
  according to the <a class="link" href="GTlsConnection.html" title="GTlsConnection"><span class="type">GTlsConnection</span></a>'s certificate revocation list.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-INSECURE:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_INSECURE</code></span></p></td>
<td>The certificate's algorithm is
  considered insecure.
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-GENERIC-ERROR:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_GENERIC_ERROR</code></span></p></td>
<td>Some other error occurred validating
  the certificate
</td>
</tr>
<tr>
<td><p><a name="G-TLS-CERTIFICATE-VALIDATE-ALL:CAPS"></a><span class="term"><code class="literal">G_TLS_CERTIFICATE_VALIDATE_ALL</code></span></p></td>
<td>the combination of all of the above
  flags
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.28</p>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.17</div>
</body>
</html>